Shareware Games Galore!/Shareware Games Galore!.iso/arcade/corewars/corewars.doc

Text File | 1989-05-02 | 20KB | 504 lines

             THE CORE WARS DEVELOPMENT AND SIMULATION SYSTEM
            ───────────────────────────────────────────────────

                   IBM PC version, Version 2.1 rev. G
                       Last revision 30-Apr-89
                     By Maz Spork, the DaneBrain

                            ──────────

┌─────────────────────────────────────────────────────────────────────────────┐
│ Copyright notice: This software is provided, free of charge, for your       │
│ benefit and pleasure. You are free to give away copies of the programs to   │
│ friends and colleagues, provided:                                   │
│                                                               │
│     - You do not charge any money for the software, distri-               │
│       bution or work associated with copying it.                       │
│     - All parts of the package are retained.                           │
│     - No part of the package is modified, and all copyright               │
│       notices are left in.                                           │
│                                                               │
│ Standard disclaimer: No guarantee follows this software, neither expressed  │
│ nor implied. The author takes no responability for any social, mental,       │
│ physical or dental damage this suite of programs may cause. There is no       │
│ guarantee that the software will be supported either (though chances are).  │
└─────────────────────────────────────────────────────────────────────────────┘

                ───────────────────────────────────────

The Core Wars Redcode Development and Simulation System disk contains software
to produce and run redcode programs.

Shipping list:

            READ.ME        -    This file (I hope)
            RCASM.EXE        -    The Redcode Assembler, converts your
                            source code into executeable format.
            RCDSM.EXE        -    The Redcode Disassembler, allows
                            symbolic printout of executeable code.
            MARS.EXE        -    The Memory Array Redcode Simulator.
            *.RDC        -    A collection of demonstration Redcode
                            programs.

The package also contains graphic drivers necessary to run MARS in graphics
mode. I am not absolutely sure I am allowed to include these. In fact, I think
the rules are, that they may be distributed if they are integrated into the
object code, not on their own. However, I write lots of programs, and including
graphic drivers would be a waste.

If you own one of the following graphics adaptors, or compatible, you will be
able to view the simulated core in real time as the battle is fought:

        * AT&T graphics adaptor
        * IBM CGA Colour Graphics Adaptor
        * IBM EGA Enhanced Graphics Adaptor
        * IBM VGA Video Graphics Adaptor
        * IBM8514 Graphics Card
        * Hercules Monochrome Graphics

If not, MARS will display information in text-format, indicating the status
of each warrior.


                             Redcode
                            ───────────

Assuming you know all about binary numbers, memory logic and machine-code (who
doesn't?), I will briefly talk about Redcode.
Ten instructions are provided, all of which take up 1 memory location. A memory
location consists of an instruction field, an A-operand field and a B-operand
field. Redcode addressing modes allow either access to them all in one go, or to
the B-field alone.

The supported instructions are:

       DAT   b        Illegal opcode, provides data
       MOV a b        Move data
       ADD a b        Add a to b, result in b
       SUB a b        Subtract b from a, result in b
       JMP a            Jump to a
       JMZ a b        Jump to a if b is zero
       JMN a b        Jump to a if b is non-zero
       DJN a b        Decrement b and jump to a if non-zero
       SPL   b        Spawn child task at location b

Assembler directives

       EQU n            EQUATE directive
       END            END directive

Addressing modes:

       $      Direct addressing (this is the assumed mode)
       #      Immediate addressing
       @      Indirect addressing
       <      Indirect with pre-decrement

All addressing is PC-relative. This means that a program can make an exact copy
of itself and transfer execution to that, without any side effects. To further
explain how the addressing modes interpret the relative addressing scheme,
consider these examples:

        0000:    mov    #0, 1    ; Move a ZERO to the B-FIELD of location 1
        0001:    dat    0        ; This gets altered

        0000:    mov    1, 2        ; Move whole location 1 to 2
        0001:    dat    1        ; This value gets moved
        0002:    dat    0        ; to here

        0000:    mov    @1, 2    ; Move indirect from loc. 1 to loc 2
        0001:    dat    2        ; This is the indirection, two locs. ahead
        0002:    dat    0        ; This is where cont. of loc. 3 gets copied
        0003:    dat    3        ; This gets moved

You probably know all this, though. It is important to realize some of the more
creative uses of the language, such as savings on program sizes and execution
times. These are important factors, as the smaller a program is, the harder it
is to seek down and kill - and the quicker it runs, the faster it will track
down the enemy. Consider:

        0000:    ...
        0001:    DJN    -1, 1
        0002:    JMP    -2
        0003:    ...

In this example, the DJN instruction uses the B-field of the JMP-instruction as
a counter. This field is normally unused. This is the crux of Redcode
programming (and of Real Programming in general).


                        The Redcode Assembler
                      ─────────────────────────

The Redcode Assembler will convert Redcode source code into MARS-executeable
binary code. It is a two-pass assembler.

Command line format:    RCASM <filename(.ext)> (?)

The assembler assumes extension .RDC, although you can override this. It will
produce two files, <filename.MRS> and <filename.LST>, which are the binary,
executeable file and listing respectively.

Source Code format
──────────────────

Each line of source code must have the format:

    (label) opcode (m)opA (m)opB ; comment

The (label) is a character string of which only 16 characters are stored. It is
optional, though ceartain directives (eg. EQU) requires it. The label should not
be followed by a colon, and must start in the first column, before any spaces or
tabs.
The opcode follows the label as defined in the above section about Redcode in
general. Likewise, the addresing modes and operands are required in the format
described in that section.
Here's an example of a well-known warrior called MICE, converted to this
assembler's format:

    ; MICE warrior (from Scientific American, sep. 1985)
    ;
    proglen    equ    dest-ptr        ; length of program without DATs
    disp        equ    3*17+2048/5    ; displacement for replications
    ptr        dat    0            ; counter value
    start    mov    #proglen, ptr    ; initialise counter to length of program
    loop        mov    @ptr, <dest    ; move one location from this to child
            djn    loop, ptr        ; loop for all locations
            spl    @dest        ; spawn child task at the new program
            add    #disp, dest    ; find new place to put a child
            jmz    start, ptr    ; test for distortion; repeat/self-destruct
    dest        dat    disp            ; location of child process

Note that the values will all be relative when assembling, with the exception of
labels, which are absolute. Thus, proglen will be 7 everywhere, but loop will
depend on the location of usage.
Also note that commas are not necessary, a source code statement might also read

    loop        mov    @ptr  <dest

If no START label is indicated, the assembler assumes that the program begins
with the first line of code.

Expressions
───────────

The assembler has a full expression evaluator, supporting plus, minus, multiply
and divide functions. Parantheses are NOT supported. The order of precedence of
these operators are:

    + -    :    0
    * /    :    1

as increasing priorities. Expressions are evaluated from left to right unless
priorities interfere. The operator stack size is 255.
A special operator, !, denotes 'current PC', and can be used in expressions like
"label-!".

Assembler directives
────────────────────

Two directives are supported for flexibility. These are:

    EQU    :    Assigns an absolute value to a label
    END    :    Terminates the source code

The EQU is useful for specifying ranges within a program under development to
reduce errors when copying parts of it. Be careful when using EQUated values in
non-immediate operands, they will not change according to current PC.
END is not necessary, but can be used when some instructions below the end of
the program are not always used.

Comments
────────

Comments must be prefixed with a semicolon, and causes the assembler to skip
characters until the next line. A comment can start anywhere on a line, and a
line can consist of a comment only.

Assembler listing
─────────────────

The assembly listing shows the formatted source code with MARS binary
instruction fields, line numbers and addresses. A symbol table is also included,
in which lower-case symbols are relative and upper-case ones are absolute.
Also, statistics about the assembly is put into the listing.

Object code
───────────

Object code is generated for reasons of speed in the simulation process. Please
note that the MARS object code for various systems (mainly 8086 versus 68K) is
not the same, and thus not compatible.

Error messages and warnings
───────────────────────────

Error messages are given in the format "error X in line Y: errortext". The
errors numbers are:

 0: Line too long:
    A line of source code has exceeded 255 characters,
    which is the maximum number allowed.

 1: Invalid opcode:
    RCASM did not recognize the opcode, and could not
    associate it with an assembler directive either.

 2: Invalid expression:
    The expression evaluator could not make sense of the
    expression. This could also be an unknown label. The
    assembler will tell what part of the expression it
    had trouble evaluating.

 3: Invalid addressing mode:
    RCASM was unable to determine the meaning of the
    supplied addressing mode.

 4: Double definition:
    A label has been defined twice.

 5: Start indicator misspelled or missing
    (not used)

 6: Out of stack space
    You have used all stack space for symbols. At present, there is nothing to
    do about this - execpt removing some labels.

 7: Too many errors
    More than 16 errors were found, and the assembly was aborted.

 8: Too few operands
    The opcode needed more operands than were supplied.

 9: Immediate addressing not allowed here
    This could be MOVing data from somewhere to an immediate value, which
    clearly makes little sense. It happens mostly in the B-field, but can also
    be JuMPing to immediate data.

10: Garbled line or too many operands
    Unrecognized junk followed the source code statement, or the line is
    garbeled or corrupted. Or perhaps you've forgotten a semicolon before your
    comment.

11: Equate directive has no label
    An EQUate directive was found, but no label was specified to which the
    result should be assigned.

In addition, two warnings exist:

 0: No start indicator, first instruction assumed
    Originally an error 5, this warning will just place the START at the first
    executeable line of code found in the source code.

 1: Program size is zero
    This is what happens if you're one of those COBOL-trained programmers, who
    write so much documentation that they forget all about writing some actual
    code. Avoid this, you'll lose the battle.

The Redcode Assembler takes an optional parameter, ?, which writes a brief list
of source code formats, allowed opcodes and addressing modes.


                       The Redcode Disassembler
                     ────────────────────────────

This program converts binary MARS-code (.MRS-files) into symbolic redcode
instructions. The command-line format is:

        RCDSM <filename(.ext)> (/a)

The disassembly is listed as adresses, object-code and symbolic redcode
instructions. Also, the START-indicator label is listed where appropriate.
The A switch allows the operands to be displayed as absolute values, enabling
quicker reference for the viewer.
As the MARS version 1.2 system itself has a built-in core disassembler, the
usage for this program is a little limited. However, when only the object code
is known (fx. the opponent's killer warrior), it can be a good utility.


                   The Memory Array Redcode Simulator
                 ──────────────────────────────────────

MARS takes two warriors into its core arena and initiates the battle between
them until one of them dies, the time runs out or the user breaks in.

The command line format is:

        MARS <warriorA> <warriorB> (<switches> ...)
        MARS ?

The two warriors must be specified, and they must be present on the disk. Do not
use pathnames in the warrior names, but if the warrior programs' extension
differ from the standard, you can use the new ones.

Execution
─────────

MARS will place the two warriors at random places in the cyclic memory. The
first program on the command line will be the first program to execute an
instruction.
The two programs then executes their programs alternately until one of them is
completely dead. If you have graphics capabilities, you will be able to view the
core in its entirety.
Dots on the screen does not necessarily denote what memory a program "owns",
they rather show where a program writes data into memory.

Termination
───────────

The battle can terminate in one of three ways:

    1. One of the warriors dies
    2. MARS times out the battle
    3. The user breaks off the battle by pressing a key

When the program is terminated by the user, a special "TERMINATION HALTED" menu
is displayed, together with information about the battle status. In this menu,
you can choose to restart the game from where you left off, you can analyze the
game, you can disassemble the core or you can terminate the battle.
When the program terminates by either timeout or death, MARS will produce an
appropriate "POST MORTEM" over the programs, how they performed, and who won. At
this point, ceartain statistics can also be asked for.
You can ask for a list of where the programs are currently placed in the core,
and you can list the programs in Redcode statements. The disassembler will
display the names of the programs' program counters as it goes along. If the
disassembly is initiated at post-mortem time, the position where the losing
warrior got killed will be tagged. It is interesting to see how programs
sometimes have mutated, and how code exist in the core with little or no
resemblance to what you originally wrote! Speak about AI!
A terminated battle is given a unique signature, enabling an identical run to be
performed, though this requires identical warriors, timeout values, execution
modes and core sizes.

Command Line Switches
─────────────────────

The command line switches are:

    C:    Set Core Size. Maximum is 32767 locations, default is 4096.
    D:    Debug mode - shows all effective addresses and instructions as
        they are executed.
    E:    Set Execution Delay * 100ms. Default is 0.
    G:    Override auto-detection of graphics card (IBM PC only).
    N:    No graphics - use text display only.
    P:    Parallel execution mode.
    S:    Set Battle Signature.
    T:    Set Timer start value. 0 for infinite time. Default 5000 clocks.
    W:    General information
    8:    Use ICWS' CoreWar'88 standard.

The switch indicator is either the slash (/) or the dash (-). An example command
line is:

    MARS MICE CHANG1 /T 8000 /P /C 2048

which tells MARS to put the warriors MICE and CHANG1 into the arena, set the
initial timer to 8000, use parallel execution mode and set the default core size
to 2048 locations.
There is no preorder demands on the switches, and the space between the switch
and the decimal number on some swiches is optional, eg. /T8000 in the above
would also be legal.
The /P switch tells MARS to execute the programs in a so-called parallel mode.
While the standard simulation scheme works with multiple tasks through the SPL
instructions, this method has a lot of drawbacks. Consider an IMP-STOMPER:

    picket    dat    0            ; Test site
    trap        dat    0            ; Trap IMPs here
    bomb        dat    0            ; Bomb value
    start    jmz    start, picket    ; Wait for the picket to change
            mov    bomb, trap    ; Kill the IMP
            jmp    start

This nifty little program will detect IMPs as they trash the picket, and
subsequently kill them at the next location. This is all fine until you want
this IMP-STOMPER to be just one task at the beginning of a larger program. In
a split-task situation, the non-parallel method will actually steal execution
cycles from the IMP-STOMPER, making it not detect the exact time of interception
by an IMP. This means that it will not function properly, and be killed.
I argue that it should not be the number of tasks running that should determine
how a program performs. In the real world, you do not move slower when you get
kids (well, perhaps you do, but that's besides the point!). When stating
parallel execution mode, EVERY task gets a cycle executed when the program has
its turn, rather than just ONE task in the sequence. Then the IMP-STOMPER will
work.
The other creative prospect is how it changes the way redcode warriors are
designed and written. Much more care has to go into the battle programs, of a
totally different kind. It is, however, much more solid this way. The 'old'
method actually only allowed one kind of warrior, the "mutilate as much as
possible, hopefully overwriting the opponent".


                        Future enhancements
                       ───────────────────────

Here's a brief list of what I just might consider doing if ample interest
develops into my version of MARS:

    * Dynamic stack sizes in RCASM
    * History buffer in MARS to allow 'backtracking' to find out exactly
      what happened up to the point where a program got killed.
    * Infinite number of tasks (or more than 64 anyway).
    * More than 2 warriors?
    * Larger core sizes with disk swapping.
    * When the ICWS finally define a good standard, implement it.
    * Interactively disassembly. Point on the graphic core with the mouse
      and select the location around which you want a disassembly.

I sincerely hope that the PARALLEL execution mode will be the new standard.
It allows so much more flexible and WORKING programs to be written, rather
than the only possible effective warrior in the non-parallel version, the
"move and multiply" program. In fact, all good programs are variants of MICE.
Also, I intend to investigate the possibilities of "shadow" tasks, in which
memory is layered to allow a task to work in conjunction on several planes.
This could be extended to make the warriors time-domain independent - ie,
a task on one layer can "see into the future" or "into the past" and decide
what to do next.


                            Source Code
                          ───────────────

If the source code for the various parts of MARS is included in the package, you
are free to look at it and add to it, though this must happen with the following
conditions:

    - The programs are my copyright, and I have placed them in the Public
      Domain. If you want to enhance or change anything, you have to follow
      me in this. Never must any money be charged for this system of MARS,
      neither in its present form or with any changes made by others.

    - You must send me a copy of the enhanced programs.

Keeping this in mind, I encourage you to enhance the programs.


                            Bibliography
                          ────────────────

A. K. Dewdney : Core Wars, Scientific American (Computer Recreations), September
1984 and May 1985

Acorn User, The Core War, October 1985

M. Spork : Slaget om Siliciummet, DataTid, september 1988

The Core War Newsletter, AMRAN Publishing (quarterly publication)


                            Addresses
                           ─────────────

I would very much like some feedback on this software. If you have any comments
or suggestions, please do write to me.

    Maz Spork, Howitzvej 21 (FLAT 2), DK-2000 Frederiksberg

The Internation Core War Society can be contacted at:

    ICWS, Office of the Secretary (!)
    5712 Kern Drive
    Huntington Beach, CA 92649-4535, USA

AMRAN Publishing (The Core War Newsletter) lives at the same address.